﻿/**
 * Copyright (C) 2011 original author and authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using NGuice.Inject.Matcher;
using System.Reflection;
using AopAlliance.Intercept;

namespace NGuice.Inject.Spi
{
    /// <summary>
    /// 描述一个被NGuice遭遇到的一个可注入类型的上下文，允许报告错误、注册注入监听器以及为可注入类型I绑定方法拦截器。
    /// 在TypeListener.Hear方法返回之后使用一个encounter是一个错误！
    /// </summary>
    public interface ITypeEncounter<I>
    {
        /// <summary>
        /// 为类型I记录一个错误（此类型I将在稍后显示给用户）。他不像抛出一个异常，他允许我们继续配置注入器并发现更多的错误。
        /// </summary>
        /// <param name="message"></param>
        /// <param name="arguments"></param>
        void AddError(string message, params object[] arguments);

        /// <summary>
        /// 为类型I记录错误，完整详细的内容将被记录日志。如果你的类型监听器调用一些你担心失败的东西，
        /// 你可以捕获异常并传递给此方法
        /// </summary>
        /// <param name="t"></param>
        void AddError(Exception t);

        /// <summary>
        /// 记录一个描述错误的消息
        /// </summary>
        /// <param name="message"></param>
        void AddError(Message message);

        /// <summary>
        /// 返回为给定注入key的用于获取实例的提供者，返回的提供者直到注入器被创建才有效。如果你在
        /// 之前使用提供者，将抛出异常IllegalStateException
        /// </summary>
        /// <typeparam name="T"></typeparam>
        /// <param name="key"></param>
        /// <returns></returns>
        IProvider<T> GetProvider<T>(Key<T> key);

        /// <summary>
        /// 返回为给定的注入泛型类型的用于获取实例的提供者
        /// </summary>
        /// <typeparam name="T"></typeparam>
        /// <returns></returns>
        IProvider<T> GetProvider<T>();

        /// <summary>
        /// 返回用于在给定的类型T中的方法和域中注入依赖的成员注入器。返回的提供者直到注入器被创建才有效。如果你在
        /// 之前使用提供者，将抛出异常IllegalStateException。
        /// </summary>
        /// <typeparam name="T"></typeparam>
        /// <param name="type">要获取成员注入器的类型（包括封装的泛型类型）</param>
        /// <returns></returns>
        IMembersInjector<T> GetMembersInjector<T>();

        /// <summary>
        /// 为类型I注册一个成员注入器。NGuice将在一个I实例拥有的注入执行之后使用成员注入器
        /// </summary>
        /// <param name="membersInjector">此参数必须是泛型参数，且泛型参数必须为I的超类</param>
        void Register(IMembersInjector membersInjector);

        /// <summary>
        /// 为类型I注册一个注入监听器。NGuice将在所有I实例的注入执行后通知监听器
        /// </summary>
        /// <param name="listener">此参数必须是泛型参数，且泛型参数必须为I的超类</param>
        void Register(InjectionListener listener);

        /*if[AOP]*/
        /// <summary>
        /// 将方法拦截器绑定到匹配类型I或其超类的方法上。拦截的合格方法为：
        /// </summary>
        /// <param name="methodMatcher">要应用拦截器的方法，例如具有Transactional标注的方法等(此参数必须是泛型参数，且泛型参数必须为MethodInfo的超类</param>
        /// <param name="interceptors">要绑定的拦截器</param>
        void BindInterceptor(IMatcher methodMatcher, params IMethodInterceptor[] interceptors);
        /*end[AOP]*/
    }
}
